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The Commodore Amiga PC Operating System is not UNDCf , nor is it Macintosh. It is unique... 
but it takes full advantage of the lessons learned from other operating systems. It is a smallj 
full bodied operating system, functioning on a small (but great) machine bound for the consu¬ 
mer marketplace. Its primary purpose is not to provide a sophisticated software development 
environment - rather it provides a foundation for pleasant and useful application programs. 
This is not to say that it neglects the programmer’s needs. Externally it is meant for end users; 
internally, however, it is designed to support the complex demands of most applications. It pro¬ 
vides extra rich functionality for an operating system of its class. 

This document is divided into two parts: 

SPECIFICATION 

This part defines the goals for this product; outlines its components, operations, 
and properties; expounds on the relationship between DOS and ROM code; and 
briefly describes implementation form requirements. 

DISCUSSION 

This part discusses the abstract concepts and structure of the operating system. 
It can best be thought of as an early draft of the operating system reference 
manual. It does not attempt to dictate the implementation detail or uncover the 
subtleties rooted in known theory. This part is incomplete — it is much too volu- 
mous to be finished in the allotted time. 



f UNIX is a trademark of Bell Laboratories. 



1. Product Goals 


The primary goals to be achieved by the Commodore Amiga Operating System (CAOS) product 
are outlined below. These goals are not listed in any particular order. 


functionality 


usablity 


programmability 


extensiblity 


reliability 


performance 


size 


maintainability 


CAOS will provide substantial functionality for a machine of the home- 
computer and personal-computer classes. # It will provide the primary 
operating and utility system functions necessary to support a wide 
variety of personal and home computer application programs. 

CAOS will be easy to use at both its outer (command shell) and inner 
(program access) interfaces. It will support the Amiga User Interface and 
adhere to its principles. It will be easily configurable and customizable for 
sophisticated users. It will be functionally consistent. 

At the command level, CAOS will provide a useful interactive and batch 
command language. This language will properly integrate with the Amiga 
User Interface. At the program level, CAOS will support a rich set of 
functions useful to application and utility programmers. 

CAOS will be constructed to ensure long product lifetime for both it and 
its applications. It will be of a modular and extensible design. Future 
enhancements can be added without affecting the useful life of the 
current application software base. 

CAOS will operate reliably to the degree permitted by the underlying 
hardware. Its data storage formats will be sufficiently protected so as to 
limit the propogation of destructive malfunctions. It will also provide 
mechanisms of protection against unintentional deletion of user or appli¬ 
cation files. 

CAOS will perform its internal operations at a sufficient rate so as not to 
be a nusiance to its human users. It will be properly tuned to take full 
advantage of the computer’s hardware and memory resident software. 

CAOS will be reasonably compact in both its main memory and disk 
resident forms. It will not occupy a significant percentage (say $%) of 
the available RAM space. 

CAOS will be written so as to be easily maintainable by operating system 
support personnel. Source code will be fully documented and readable to 
a moderately trained professional. 


2. Components, Operations, Properties 

This section specifies the individual components, operations, and properties expected to exist in 
the Commodore Amiga Operating System. These specifications are presented in an outline form. 
(A complete description would resemble a user reference manual in both content and size — 
unfortunately there is not the time to complete such an approach. Refer to the discussion part 
of this document.) 

This specification is expected to generate a number of design issues (especially from people with 
differing backgounds). 
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The Commodore Amiga Operating System will provide and support 
the following: 

1 - file 

.. major types 

... ordinary files 
... directories 

.... hierarchical 
... special files 
.... devices 
... image files 
.. identification 

... string of any characters except null 
... full path names (with volume name) 

... current directory relative names 
.. access controls 

... general permissions 
.... read 
.... write 
.... execute 
... modes 
.... read 
.... write 
.... append 
.... exclusive 
... asynchronous access 
... enforced restrictions 
.... writing directories 
.... removing special files 
.. operations 
... open a file 
... close a file 

... read a number of bytes 
... write a number of bytes 
... seek to given position 
.... byte addressible* 

.... relative to 

.start 

.end 

.current position 

... link to file 

.... hard (link to file data) 

.... soft (link to file name) 

... get file size 
... detect end of file 
... truncate part of a file 
... update physical form 
... lock/unlock access 
.... read lock 
.... write lock 
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... get last error 
... other control 
.. information 
... description 
... creation time and date 
... update time and date 
... link count 
... permissions 
... file type 
... user id 
... size 
.. limits 

... file size 

... name size 

... path size 

... number of files 

... number of open files 

... simultaneous accessors 

... restrictions 

2 - volumes 
.. identification 
... name 

... just like file name 
... always under (root directory) 
... serial number 
... unique 
.. types 
... online 
... offline 
.. information 
... description 
... creation time and date 
... update time and date 
... number of files 
.. protection 

... removal detection 
... write protect 
.... hardware 
.... software 
.. block allocation 

... minimize read, write, and seek time 
.. block buffering 

... minimize number of accesses 
... configurable number of buffers 
.. prompting for 

... offline volumes 
... new volumes 
.. limits 

... online 
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... offline 

3 - device support 
.. types 

... structured random (e.g. disk) 

... structured stream (e.g. tape) 

... unstructured random (e.g. display) 

... unstructured stream (e.g. keyboard) 

.. access 
... as a file 

.... uses file operations 
... directly 

.... io control blocks 
.... as with ROMs 
.. dynamic configuration 

... removed when memory needed 
... reloaded when required 
.. request control 

... asynchronous requests 
... request queuing (more than one request) 
... abort request 
.. operations 

... initialize a device 
... open access 
... close access 

... read a given number of bytes 
... write a given number of bytes 
... update buffers 
... reset 

... stop when finished with current 
... stop now 

... check memory allocation 
... get status info 
... other control 

.. form is identical to ROM devices 

4 - memory management 
.. types 

... regions 
... subregions 
... segments 
.. regions 
... static 
... fixed position 
.. subregions 

... relatively static 
... deletable 

... relocatable (statically) 

... sharable 

... managed by system 
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.. segments 
... dynamic 
... deletable 

... relocatable (dynamically) 

... overlayable 
... descriptor access 

... managed by application (system helps) 

.. packages ?? 

5 - multiprocessing 
.. virtual processors 

... all processor registers 
... processor exceptions 
.. context 

... run entirely in user mode 
... single user mode stack 

... system maintained independent environment 
.. identification 
... name 
... path 

... global descriptor 
.. loading 

... code relocation 
... data relocation 
... overlay manager 
.. scheduling 

... highest priority runs if ready 
... same priority round robin on set quantum 
... use ROM functions 
.. resource tracking 
... all resources used 
... releases on process termination 
.. mutual exclusion 

... interrupt exclusion 
.... disable 
.... enable 
.... nesting counter 
... task exclusion 
.... forbid 
.... permit 
.... nesting counter 
.. interprocess synchronization 
... event signals 
.... task relative 
.... pre-signalled events 
.... selective disables 
.... any signal of many will wake 
.... can cause exception 
... use ROM functions 
.. interprocess communications 
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... message ports 

.... process private 
.... system global (for rendezvous) 

.... cause event signals 
... messages 
.... direct 
.... buffered 
.... replying 
... use ROM functions 
.. standard input/output/error files 
... inherited from parent 
... redirection 
.. exception handling 
... context 

.... specially designated user code 
.... recursive exceptions allowed 
... types 

.... all 68000 processor exceptions 
.... event signals 

.... arbitrary user defined exceptions 
.. timers 

... use message replies 

... timing provided with timer device 

6 - startup and shutdown operations 
.. boot devices loaded and initialized 
.. time and date setup 
.. user configuration file 
.. startup auto-execution file 

8 - user interface support 

<< not defined in this document >> 

9 - general utilities 

.. clock and calendar 
... ticks since base date 
... time of day 
... date 

... numerical day of month, month, year 
... day of year (julian), year 
... date string formatter 
... signal process on clock/date time 
.. disk volume copier 

... utilizes maximum memory 
... verification support 
... volume auto-formatting 
... volume auto-naming 
... new creation date 
.. volume creation 
.. volume naming 
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.. directory file creation 
.. file listing 

... accepts wild cards 
... short 
... detailed 

... sorted various ways 
.... creation date 
.... update date 
.... size 

.... permissions 
..file copier 

... transfer with special files (devices) 
... volume spanning 
... recursive directory creation 
... accepts wild cards 
... concatenation 
... verification support 
.. file mover 

... transfer with special files (devices) 
... volume spanning 
... recursive directory creation 
... accepts wild cards 
... verification support 
.. file deletion 
... wild cards 

... recursive directory deletion 
.. file restorer 

... restore deleted files 
... restore trashed file systems 
..file control 

... changing modes 
... changing dates 
.. file statistics 
... size 
... dates 
... permissions 
..file comparison 
... difference 
... common 
.. file printer 
... page breaks 
... page heading 
.... file name 
.... current date 
.... selectable file dates 
.... page number 
..file conversion 
... detabbing 
... entabbing 
... run length encoding 
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.. pipes (if they don’t cost much) 

.. system control 
... process killing 
... I/O abort 
... device stopping 
.. system statistics 
... free memory 
... free disk space 
... process states 
.. environment control 
... subregion size 
... stack size 

.. environment statistics 
... current directory 
.. disk integrity checkout 
... bad blocks 

.. file system integrity checkout 
... bad linkage 
... bad sizes 
.. pattern searcher 
.. configuration aids 
.. string utilities 

certain properties and functions are implied. O.S. professionals - know and accept implied por¬ 
tions 

many important design decisions to be made — we have not the time nor the manpower to prop¬ 
erly evaluate alternatives — implementer should do so. 


3. EXEC 

The much of the higher level operating system implementation depends on the lower level ROM 
executive (commonly called EXEC). The primary purpose of EXEC is to: 

- provide power-on (coldstart) system initialization 

- create an intermediate system environment suitable for the bootstrap 
of 

* disk operating systems 

* stand-alone disk-based applications 

* remote software development 

* hardware diagnostics 

- perform rudimentary power-on testing and diagnostics 

- centralize and regularize the handling of system interrupts 
and exceptions 

- define the lower levels of device control and interfacing 
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- handle fatal system errors and post appropriate diagnostic messages 

- provide a means of function access that is both maintainable 
and extensible 

- increase overall system throughput by supporting program concurrency 

- supply fundamental timing and synchronization operations 

- provide a set of useful utility functions 

- support a minimal debugging environment 

- otherwise regulate the basic hardware resources of the 
machine in conjunction with several hardware specific libraries 
(graphics, sound, etc) 


4. Target User 

The target user for this machine is the person with minimal or no computer experience. There 
are special requirements for this marketplace. For these people the system must be quite forgiv¬ 
ing. 

In addition, this machine will likely be used by many ’’small-time” applications programmer for 
development. 

[high volume production: high replacement and upgrade costs] 


5. Design 

Implementation must take full advantage of the hardware and be fully integrated with the 
ROM software. 


5.1. Calling ROM functions 


5.2. Memory Usage 

Small size -- probably will require assembly code. 
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5.3. Internal Documentation 


5.3.1. Modules 

All modules will include a document header containing the module name and a copyright notice. 
For example: 


(XMSiODORE AMIGA HOME COMPUTER =- 


DISK OPERATING SYSTEM 


Memory Allocation 


Copyright 1084, Commodore Amiga, Inc. All rights reserved. 
No part of this program may be reproduced, transmitted, 
transcribed, stored In retrieval system, or translated Into 
any language or computer language, in any form or by any 
means, electronic, mechanical, magnetic, optical, chemical, 
manual or otherwise, without the prior written permission of 
Comnodore Amiga Incorporated, 3350 Scott Blvd, Bid #7, 

Santa Clara, CA 05051 


This header should be immediately followed with the module’s include files and import/export 
declarations. 


*** Included Flies ***» 

INCLUDE IA.Consts 

INCLUDE IA3*acros 

INCLUDE I A_Ty pe s 

INCLUDE IA.Structs 

*** Imported Globals * 

EXTERNAL MemL 1 s t 
EXTERNAL msgBadFree 
EXTERNAL ms gCo r r u p t 

*** Imported Functions 

EXTERNAL Panic 

'*** Exported Functions 

GLOBAL A1 locate 

GLOBAL Deallocate 
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5.4. Function Headers 

All external functions must be supplied with a descriptive header. This header contains the 
function name, a synoptic form, descriptions of the function, it parameters, and results, a 
definition of exceptional conditions, and references to related functions. For example: 


Sy s t em/Al locate 


NAME 

Allocate -- allocate a block of memory 
SYNOPSIS 

memoryBlock = allocate(freeLlst, byteSlze) 

DO AO DO 

FUNCTION 

This function Is used to allocate blocks of memory 
from a given free memory pool. It will return the 
first free block that Is greater than or equal to 
the requested size. 

All blocks, whether free or allocated, will be block 
aligned; hence, all allocation sizes are rounded 
up to the next block even value (e.g. the minimum 
allocation resolution is 8 bytes). 

Th Is function, wh en used in conjunction with a private 
free list, can be used to manage an application's 
internal data memory. 

INPUTS 

freeLlst - points to the memory list header 
byteSlze - the size of the desired block in bytes 

RESULT 

memoryBlock - a pointer to the Just allocated free block. 

If there are no free regions large enough to satisfy 
the request, return zero. If the amount of requested 
memory Is Invalid, return zero. 


EXCEPTIONS 

If the free list is corrupt, the system will panic. 

SEE ALSO 

Dea1 locate 


5.5. Code Blocks 


Blocks of code that form a logical group need a brief explanation: 
A loop for example: 


dels 


I. 

MDVE.L 

BEQ.S 

CMP.L 

BCS.S 

MDVE.L 

BRA. S 


scan for position in free list: 


[ A2 ] ,D3 
head_check 
D3 , Al 

head.check 
D3 ,A2 
del 


; get next node address 
; end of list 

; went past returned region? 
; add region to free list 
; on to the next node 
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or just a sequence of instructions: 

round size up to even block address: 
ADDQ.L ^!Dvl_BIX)aK\l\SK,DO ; bias 
AND.L D3 ,D0 ; round 

Individual lines should be documented as appropriate. 
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1. Files 


A file is an abstract data object with a standardized set of access methods. A file is an abstract 
data object because it appears to the user to be a consistent (regular) data stream regardless of 
its underlying storage form or physical device type. A file may reside on a disk, flow over a net¬ 
work, collect from a keyboard, or spew to a display — all without special knowledge or aware¬ 
ness on the part of the user. 

Providing a file system is the most important goal of the disk operating system. 


1.1. Types of Files 

The file system supports four types of files: ordinary files, directory files, image files, and special 
files. 

An ordinary file stores data on some physical media for later use. Ordinary files can store what¬ 
ever type of data necessary: ascii character strings, program object binaries, raw numeric data, 
etc. There is no system imposed structure on the contents of an ordinary file. 

Directories are files which map string names to actual data content. They differ from ordinary 
files because their content conforms to a particular system structure and they are specially pro¬ 
tected against accidental over-writing. A directory may include the names of files which are 
themselves directories — which may in turn include the names for yet other directories — on and 
on and on. 

Image files provide a symbolic method of binding to system internal data objects. Because of 
the great regularity of Exec structure lists, and because each element in a particular list has an 
name string, it is possible to gain access to a structure by just knowing its name and node type. 
Access to such structures is consistent with all other types of files; however, the layout of an 
internal structure depends on its type. When a read operation is performed on this type of file, 
a copy of the data object is made in the user’s buffer. [Can the local file descriptor be used for 
object related functions. For example, can the file descriptor for a port be used to send messages 
to that port.... this has a certain appeal to it! It might also reduce the need for specialized func¬ 
tions.] 

Special files are accessed just like ordinary files, but they do not necessarily represent data 
storage media. Instead they provide standard access to I/O devices. Making devices act like 
ordinary data files adds a great amount of consistency to system and helps reduce program com¬ 
plexity. Special files offer the same naming, protection, and function access mechanisms 
afforded ordinary files. 

1.2. Names and Paths 

It is worthwhile to note that the following name conventions are useful primarily to the pro¬ 
grammer. Names and paths have little meaning to the end user, who performs most of his file 
specifying by pointing the mouse and pushing a button. The user will describe a file as being in 
that particular folder within that particular file cabinet. 

An actual file name (as stored in a directory) may include up to 30 characters. File names may 
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include any character except null. 

A path name on the other hand includes a string of one or more file names each separated with 
a ”/” character. A path specifies the directory hierarchy to be searched when referencing one or 
more files. 

A path may be specified relative to the system root directory or relative to the current working 
directory. Starting a path name with ”/” indicates that the path is relative to the root. 

The reserved file name refers to the current directory. The reserved file name refers to 
the parent of a specified (or current) directory. 

A path name may not exceed 255 characters in length. 

1.3. Pattern Matching 


more... 


1.4. Hard and Soft Links 

A file name is bound its actual file content with what is called a link. There can be more than 
one link to any given file. [Do we need to make directories an exception to this rule? Not 
allowing it may cause problems with the packages concept.] Hence, the same file may be refer¬ 
enced under multiple names. No special treatment is given to the original name of the file. 

A hard link references a file by actually pointing to its internal data structure. A directory is 
just an array of hard links. A hard link requires that the internal file structure maintain a 
reference count to know when to actually remove a file. 

Soft links reference files by preforming a textual substitution on the file name. A soft link can 
be thought of as a macro which gets expanded when the file name is referenced. The big advan¬ 
tage of soft links is that they can span file systems. This is of great use for networked 
machines. 


1.5. File Information 

For every file the DOS maintains useful access, state, and user defined information: 


description user defined string from 1 to 255 characters which contains a short description 

for reference purposes. [The operating system may store these strings in some 
remote part of the storage media — making them slow to access but getting 
them out of the way.] 


creation time 


date and time the file was created. 


update time 


date and time the file was last modified. 
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link count 
permissions 

type 
user id 

size 

blocks 


the number of hard links to the file. 

what type of file access is allowed: read, write, or execute. Also indicates 
whether file is open for exclusive access (locked). 

indicates whether file is a directory, printable, non-printable, ... [what else?] 

[?required?] specifies the user that created this file. This is useful mainly to 
applications which want to keep the home user from inadvertently destroying 
an important file. 

the file size in bytes. 

the number of blocks allocated to the file. 


This information can be referenced through the appropriate system functions. 

Image and special files do not maintain all of the above information. Certain default values 
may be returned in such cases. [Although it would be nice to keep such information for selected 
image files, e.g.: process creation date and time.] 


1.6. Access 

A file may be opened for reading, writing, and appending. 

If a file can be opened by more than one process at the same time. DOS maintains separate 
position markers for each instance. 

[blocked vs character] 

more... 


1.7. Positioning 

Ordinary files are randomly byte addressible. Any byte may be addressed in any order. 

The file system maintains a position marker to assist in reading and writing. This marker is 
moved automatically when reading or writing a file. Opening a file for reading initially places 
the marker at the beginning of the file. Opening a file for writing does the same. Opening a file 
for appending places the write marker initially at the end of the file. 

1.8. Image files 

The DOS file system provides a useful means of accessing files bound to certain names. Image 
files let the file system also be used to access internal system objects which are bound to certain 
names. These objects may be libraries, processes, tasks, interrupt handlers, interrupt servers, 
devices, ports, or what have you. The file system is essentially being used as a symbolic address 
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space. 

When an image file is opened, a descriptor is returned which may be used as a handle on the 
desired data object. Reading from this descriptor will copy the object into the user’s own 
buffer. 

The descriptor may also be used for special functions used to control the related object. 

[Functions which normally task global descriptors might be able to detect local descriptors — 
they’re not in descriptor space. This might be useful.] 


1.9. System Directories 

The system maintains a few directories for its own use. The /, /dev, and /exec are just such 
directories. 


more ... 


1.10. Limits 

The number of files is not limited in concept only in practical implementation. Maximum 
number of descriptors, links, names, file size, blah blah ... 

[Allocation, layout of disk volume -> see disk device? Buffering of partial blocks.] 
more... 


1.11. Integrity 

File system integrity must be protected through the proper mutual exclusion mechansims. 
The use of checksums for important filesystem structures may be of value. 


1.12. Reliability 


more... 


1.13. Function Descriptions 

File functions are subdivided into three sections: high level functions which provide a comfort¬ 
able and safe means of file access; primitive file functions which operate directly on file control 
blocks (and upon which the entire filesystem is built); and support utilities which are more 
related to file organization and maintenence. Each of these is covered in a separate section. 

File system will functions are accessed through the DOS library interface. As with Exec the 
library interface will be at the assembly code level. 
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1.13.1. File Access with Descriptors 

Descriptor based file operations are the easiest means for the application programmer to access 

DOS files. With the use of descriptors the file control block is invisible. The functions 

described in this section should satisfy most programmer’s needs. 

These functions are internally implemented with the file functions described in the next section. 

Open Open a file of the given name (includes path) and return a descriptor for that 

file. Various options may be specified: read-only, write-only, read and write, 
append, create, careful- create, exclusive. Opening with the create option will 
cause truncation of the file if it already exists. This action can be prevented 
with careful-create, which will fail if the file already exists. Careful-create can 
be used as a simple means of exclusive access. A successful open will return a 
positive integer as the file descriptor. If an error occured, a -1 will be 
returned. There is a restriction on how many files may be simultaneously 
open for any process. 

Close Close a file and free its descriptor for reuse. If this was the last reference to a 

shared file, cleanup its state and, if necessary, perform an update. If the file 
was locked, release its lock. Exiting a process will perform an implicit Close() 
on all open files. 

Read Attempt to read data from a file into the buffer specified. Length indicates the 

maximum byte size of the transfer. The actual number of bytes read may be 
less than what was requested if any one of the following conditions occurred: 
end of file; line termination (set by Control(])\ i/o timeout; or file error. For 
the last two cases a -1 will be returned. The ErrorCode() function may be 
called to determine the type of error. A successful return will increment the 
internal pointer by the number of bytes actually read. Read() may operate 
either synchronous or asynchronous depending on the options specified by 
Controlf). Seek() can be use to read from a given position in a file. 

Write Attempt to write data from the buffer to a specified file. Length indicates the 

maximum byte size of the transfer. The actual number returned will be -1 if 
any one of the following conditions occurred: i/o timeout; or file error. The 
ErrorCode() function may be called to determine the type of error. A success¬ 
ful return will increment the internal pointer by the number of bytes actually 
written. WriteQ may operate either synchronous or asynchronous depending 
on the options specified by Controlf). Seek() can be use to read from a given 
position in a file. Because data is internally buffered by the operating system, 
a write may not actually occur on the physical device associated with the 
given file. This internal optimization can be over-ridden by following the 
Write with an Update. 

Seek Seek to a given byte offset in a file. This offset is based on the relation 

specified. It may be either absolute (relative to the beginning of the file), rela¬ 
tive to the current position, or relative to the end of the file. Subsequent 
action in the associated device may or may not occur depending on the 
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current state of internal affairs. Seeking on certain types of files may not be 
permitted. Upon successful completion, the actual value returned is an offset 
from the beginning of the file. If an error occurred, a -1 is returned. To 
obtain the current position of the file pointer, seek 0 bytes in the relative to 
current position mode. This is the position from which the next character is 
read or to which the next character will be written. 

EOF 

Return a -1 if the current position is at the end of the file; otherwise, return a 
zero. This function is useful for devices like the keyboard, which may return 
a zero when read, but are not at the end of file. 

Size 

Return the total size of the file in bytes. This figure does not depend on the 
current buffer state of the file. 

Truncate 

Chop a file down to the size indicated. Data beyond the new end of file is 
lost. The file must be open for write access. The new size of the file is 
returned upon success; otherwise a-1 is returned. 

Update 

Forces output of all dirty buffers to the device associated with the given file 
descriptor. Directory entries corresponding to the file will also be updated. 

Name 

Return a pointer to the file name related to a descriptor. 

Options 

Return the current options associated with an open file. These are the options 
as specified when the file was opened. 

Lock 

Prevent simultaneous file access for as long as the file is locked or open. If 
the lock is already locked, a -1 is returned. Closing the file will automatically 
release the lock, [what happens when we crash with a locked file?] 

Unlock 

Unlock a previously locked file again allowing simultaneous file accesses. 

LastError 

Return the error condition as set by the last operation associated with this 
file. If the last operation caused an error, return an error code. If no error 
occurred return zero. 

Control 

Perform miscellaneous file control. This function can control the operating 
characteristics of file access. 


1.13.2. File Access with Control Blocks 

These are the lower level file functions which require a file control block (fcb) instead of a 
descriptor. These are useful for the advanced programmer who wants to perform extended 
operations by directly manipulating file control blocks (asynchronous i/o, timeouts, ...). 


MapFile 

Return a pointer to the file control block associated with an open descriptor. 
This provides a means of getting to the internal control and state information 
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of an open file. 

OpenFile 

Open a file as described in Open() above. The specified file control block is 
initialized upon successful open. 

CloseFile 

Close a file as described in Close() above. 

ReadFile 

Attempt to read data from the given file. The buffer location, data offset, and 
transfer length are all specified within the file control block. The error field of 
the fcb should will be zero upon successful completion of the read. The actual 
number of bytes transfered is also contained within the fcb. 

WriteFile 

Attempt to write data to the given file. The buffer location, data offset, and 
transfer length are all specified within the file control block. The error field of 
the fcb should will be zero upon successful completion of the read. The actual 
number of bytes transfered is also contained within the fcb. 

Update 

Update the file state. This means updating the related directory entry as well 
as writing out all of the files dirty buffers. 

1.13.3. 

File Related Utilities 

Link 

Form a hard link to a file. The filenames can include the paths. 

SoftLink 

Form a soft link to a file. 

Remove 

Remove the entry for the named file from its directory. This function can also 
be thought of as Unlink. 

Rename 

Cause fromname to be renamed as toname. If toname already exists, remove 
it first. 


FileInfo,SearchDir,CurrentDir,ChangeDir,MakeDir,... 

more... 
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2. Volumes 

Volumes are logical or physical storage media. Disks, disk partitions, data networks, specially 
structured memory can all be volumes. 

The DOS supports multiple volumes. 


2.1. State 

Volumes are accessible once they come online. Disk and network volumes become online when 
their volume identification structure has been successfully read and verified. For floppy disk 
volumes this happens usually happens automatically within one second after a disk is inserted 
and the door closed. 

When access to a volume is severed, the volume becomes either absent, offline, or critical. 

A newly severed volume is absent when the internal state of the volume is self consistent and all 
access is concluded. A disk volume with all of its files closed and its disk removed is an example 
of an absent volume. 

A volume is offline when it is internally self consistent but further access is required. This hap¬ 
pens when more volumes than the hardware can support need to be accessed. Offline volumes 
are not necessarily a problem. It is often quite convienent for DOS to keep track of a user’s 
offline volumes. A disk volume with open updated files and its disk removed is an example of 
an offline volume. State information for offline volumes is minimal compared to online or criti¬ 
cal volumes. 

A volume is critical when its internal state is not consistent. For instance a disk volume 
becomes critical if it is removed before its volume state information block and directory blocks 
have been properly updated. This can happen to a disk volume if it is removed before its access 
light shuts off. A critical volume must be immediately re-inserted if problems are to be avoided. 

In all of the above cases, further access to the volume is not permitted until it is again online. 
An pplication which attempts to perform a file access with an offline volume will cause the sys¬ 
tem to prompt the user to insert the appropriate volume. 

Note: a floppy is considered ’’removed” immediately upon opening the drive door. 

2.2. Identification and State 


2.2.1. Names and Serial Number 

Volumes are identified by name or by serial number. 

A name is a non-empty character string with a maximum size of 30 characters. The volume 
permanently maintaines this string in its volume identification area. 
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A serial number is a hash of the volume name and the current date and time. If the serial 
number is known it is a much better than the name for identifying a volume. 

An application may explicitly reference a volume or a file on a volume by prefixing the file name 
with ’/’. If the volume is absent or offline, the system will prompt the user to put it online. A 
volume serial number may be used in place of the name. 

2.2.2. Volume Description 

In addition to the name, a volume maintains a user created description of the volume’s use or 
purpose. This description is limited to a maximum of 255 characters. 


2.2.3. Time Stamp 

Every volume maintains the date and time its creation. 

[update date and time?] 

more... 


2.2.4. Write Protection 

Volumes may be write protected by mechanical means or by system software. Mechanical write 
protection is provided as a feature of the disk drive itself. The drive detects the position of a 
tab located on one corner of the disk. 

Software write protection is provided by an access permission scheme similar to that used for 
files. A volume may be designated as read only by ??? [what is the duration of software portec- 
tion? does there need to be a temporary form of write protection that is not recorded on the 
volume?] 

If a user attempts to write to a file on a protected volume, the write will fail and an error mes¬ 
sage will be returned. 


2.2.5. Direct Access 

It is possible to access a volume directly by using its associated device special file. 
more... 
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3. Devices 

The device model provides a data abstraction for simplifying access to the multitude of input 
and output devices. It provides encapsulation of the access methods and internal state necessary 
to produce useful results. 

There is a single device model that spans the entire system. There are no structural differences 
between DOS devices and ROM devices -- they externally appear identical. 


3.1. Hierarchy 

Although all devices are similarly structured, conceptually there exists a hierarchy of devices. 

3.1.1. High Level Devices 

High level device types are those commonly used by programs. They offer extra convenience, 
function, and protection compared to low level devices. They may also provide a certain 
amount of device independence not found in low level devices. 

High level devices usually depend on lower level devices. They do not control or communicate 
with the hardware directly. They often implement the buffering mechanisms, process sharing 
techniques, access scheduling, and optimization algorithms to best utilize one or more lower level 
devices. 

The floppy disk device is an example of a high level device. It optimizes access and buffers data 
which are eventually passed on to the lower level Portia disk device. 

3.1.2. Low Level Devices 

Low level devices translate higher level actions into hardware control signals and higher level 
data into physical data formats. When possible they control the I/O hardware directly; other¬ 
wise, they access hardware through the use of shared resource libraries. 

Low level devices usually provide the interrupt handling procedures necessary to properly con¬ 
trol a device. 

The Portia disk device is a good example of a low level device. It is passed an I/O control block 
which indicates a data buffer, a transfer size, and a byte offset location. The data buffer must 
be broken into appropriate sector chunks and translated into the physical disk format. The 
device needs to convert between byte offset and physical sector/track/head location. It also 
manages the track buffering necessary when transfers span multiple tracks. In additon it sets 
up the disk DMA, services disk DMA completion interrupts, controls head motion, powers the 
motor on and off, detects disk removal, etc. 

The keyboard device is another example of a low level device. It processes raw keycodes which 
are signalled via interrupts translates them into ascii characters and buffers them as necessary. 
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3.2. Access 


3.2.1. File Oriented 

As discussed in the File chapter, special files often represent I/O devices. Opening a special file 
returns a file descriptor like any other file. This descriptor can be used to access the device as if 
it were actually a file. This provides (to some degree) a device independent access mechanism. 
The file system handles the interface to the actual device code. The usual open, close, control, 
seek, etc. commands can be used. This type of access probably accounts for about 80 percent 
device type I/O. 


3.2.2. Direct 

The operating system and an occasional sophisticated process will need to make I/O requests to 
the device directly. As described in the EXEC manual, this is done by sending the device an 
I/O request message. This message contains the device address, unit address, command 
number, and command related parameters. This message is sent via DoIO for synchronous 
operations and SendIO for asynchronous operations. 

This type of I/O can be performed by opening the device special file. The resulting descriptor 
must be passed to a system function along with a fresh I/O request block. The system will ini¬ 
tialize the control block as appropriate. This block can then be used with DoIO or SendIO 
(assuming that the rest of the block is set up by the program). 

See the EXEC manual for more information. 

3.3. Devices and Units 

A device defines a class of operations and states. It contains the actual code that implements 
the device commands. It also includes any shared data or common data for multiunit devices. 
Devices are initially identified by name. 

A unit is an instance of a device. It maintains the current state information related to the par¬ 
ticular device instance. Units are identified by number. 

3.4. Shared 

It is not always possible for a low level devices to directly control a piece of hardware. This is 
often the case when a single hardware element controls multiple hardware resources. If non¬ 
cooperating software tasks attempt to use such hardware directly, they may find the hardware 
acting in confusing and unpredictable ways. The integrity of the system as a whole will be 
jeopardized. 

These problems can be prevented by software convention through the use of access and control 
protocols. Special functions are provided for tasks needing to access shared hardware. These 
functions are encapsulated in a library fashion: a set of code vectors and a private data area. 
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The code vectors jump to access and control functions. The data area is used to store hardware 
and internal state information. 

The 6526 interrupt status registers are a good example of where this type of control is required. 
Accessing one of these registers to determine which interrupt has occurred clears all 6526 inter¬ 
rupts. Device code wishing to know whether a particular interrupt has occurred will unavoid¬ 
ably trash the status of other interrupts. To avoid this the device can call a resource accessor 
function which reads the interrupt register and maintains a private copy of the state. The 
requesting device is returned what it required without destroying information needed by others. 


3.5. Device Stubs 

It is not possible to anticipate all types of hardware devices that may ever exist on this 
machine. In an attempt to accomodate new physical devices there exists a way of identifying 
any arbitrary piece of hardware. 


more... 


3.6. Initialization 

During the ROM system bootstrap, EXEC builds an array of all known drivers and libraries 
(whether ROM resident and or add-ons). This is done by scanning all appropriate address 
spaces for a predefined pattern. 

Some of these devices may be flagged a bootstrap devices. 

During initialization, the DOS will merge this array with its own device table, 
more... 

3.7. DOS Functions 

The functions provided to access devices from DOS those described in the File chapter. 

3.8. Device Commands 

Every device class provides at least the following device independent commands. 


init 

initialize 

open 

open access 

close 

close access 

read 

read data 
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write 

write data 

update 

update buffers 

reset 

reset like new 

quiet 

stop when finish with current queue 

raided 

memory relocated or deleted, check it 

halt 

stop now 

control 

special instructions 

status 

return status information 
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4. Memory Management 

The memory manager controls the static and dynamic usage of main memory (RAM). This 
includes control of local, expansion, and (in some cases) cartridge memory spaces. The memory 
manager regulates the allocation and deallocation of memory regions, subregions, and segments; 
the sharing of code and data subregions and segments; and the compaction of subregions and 
segments through mechanisms of relocation and deletion. 

The memory manager implementation is simple, yet flexible. This is achieved by allowing each 
application to fully charcterize and control its runtime memory enviroment. 

4.1. Structure 


4.1.1. Regions 

Upon coldstart, main memory will be sectioned off into major partitions called regions. These 
regions are static because they are not easily deleted, expanded, or moved during the life of the 
system. They contain resident data structures and code which are essential to system opera¬ 
tion. Example regions are: the 68000 CPU exception vectors in low memory; the Exec ROM sys¬ 
tem library; the supervisor stack; and the main data segment of DOS. 

Given a certain amount of knowledge and care, devices, libraries, operating systems, and appli¬ 
cations can create new regions as necessary. The best time to create a new region is immediately 
after system coldstart when most of memory is free for use. 

Each region is known to the system by the presence of a link node (a descriptive header), which 
may or may not reside within the region. The system maintains substitute nodes for all regions 
that are not able to contain a node. 

The dynamic allocation and deallocation of regions can cause severe memory fragmentation and 
is not encouraged. 

Regions can support non-contiguous address spaces. 


4.1.2. Subregions 

Memory regions are futher divided into dynamic partitions called subregions. On the minimal 
system there is typically one large region which is available for subregion allocation. Subregions 
themselves are usually large units allocated for system data structures, buffer pools, libraries, 
devices, processes, shared memory, application code, application data, and program stacks. 
Once a subregion is allocated, its memory becomes unavailable to the system as a whole. 

Typically, allocated subregions will come and go depending on the mix of devices and programs 
in use. Subregions are not the unit of memory allocation used within most programs (see seg¬ 
ment section below). Generally, programs are allocated two or three subregions at load time. If 
there is not enough space for the load-time subregions, the load will be aborted and the user or 
program will be informed of the error. 


14 


Commodore-Amiga Confidential 


Operating System Specification 


Memory Management 


Depending on the circumstances, a region may eventually become fragmented between subre¬ 
gions. If this fragmentation becomes extreme, very few programs may be loadable, and the sys¬ 
tem may become quite unproductive. To avoid this situation, the memory manager may need 
to perform an occasional compaction and garbage collection of subregions within the tight 
region. The system will first attempt compaction by deleting subregions marked as volunteer 
overlay candidates. If this fails to free enough memory, subregions with with no users (reference 
counters at zero) will be deleted. This includes non-active libraries and devices. If this fails, a 
special subregion entry point will be called for relocatable and unloadable subregions. These 
subregions will then attempt to unload or relocate. Their success will depend on the state of 
their resource access semaphores. 

To help reduce thrashing, the operations described above will be performed on subregions in a 
prioritized order. 

Within subregions memory blocks can be allocated and deallocated in any order. 


4,1.3. Segments 

When a program is executed, it is allocated one or more subregions for code and data storage. 
Often programs will need to perform memory management within their own subregions. This is 
accomplished by dividing subregions into segments. Segment availability and usage is directly 
controlled by the program. Segments can be marked as relocatable or fixed, permanent or reus¬ 
able. A segment is considered locked when it is both fixed and permanent. 

If subregion memory gets badly fragmented, the system will attempt to join fragments by com¬ 
pacting relocatable segments and by deleting reusable segments. Locked segments can cause 
blockage to the compaction algorithm. To avoid this, the memory manager will do its best to 
keep locked segments together at either the top or the bottom of the subregion. 

Segments have another advantage: when dirty, they can be written out to a preallocated file on 
disk. This facility povides a handy means of checkpointing and a crude means of swapping. 

Segments are read in from disk when requested. For code segments this action corresponds to a 
simple overlay. Function call faulting overlays can be implemented on top of this by language 
providers, or by using EXEC libraries. 

Most actions that happen to segments occur through explicit function calls. The only invisible 
action is that of compaction. 

4.2. Sharing 

A simple form of code and data sharing is provided by the EXEC library mechanism. A more 
elaborate scheme utilizing semaphores is quite handy. 

One of the big problems with sharing is what to do when the shared resource needs to be 
deleted, but is still in use. Programs waiting for the resource semaphore and programs that 
currently own the resource will need to be told that the resource has been deleted. 

{note: semaphore list pool holds pointers to processes queued for semaphore. PCB is not 
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directly linked.} 

[kernel memory, separate code and data, ...] 


more... 


4.3. Packages 

The package subsystem provides a simple, yet flexible way to describe the load and run time 
memory environment for an application. It gives the user a way of binding application program 
and data files into an easy to manage form. 

At program load time the .package file will be converted into a memory resident structure used 
by the package manager. All of the load time file references will be loaded into memory as 
specified. Unresolved references will be loaded or linked as necessary. 

During the course of execution, package files will be loaded upon request. This is done by refer- 
ing to the file by name. If an file with that name is not found, other paths are checked. 

Copying a package will result in the transfer of the complete set of referenced files. 


more... 


4.4. Functions 


more... 


16 


Commodore-Amiga Confidential 


Operating System Specification 


Processes 


5. Processes 

Processes provide independently executing virtual Amiga personal computers. 


5.1. Relation to Exec Tasks 

EXEC provides the data structures and control primitives required for fast and efficient CPU 
multiplexing among any number of tasks. This includes primitives for the support of intertask 
communications and synchronization in addition to the usual task queuing, scheduling, context 
switching, and mutual exclusion. EXEC does not attempt to provide a complete program exe¬ 
cution environment. 

Processes provide a layer of abstraction and extended functionality on top of the EXEC task 
mechanism. Tasks are a subset of processes. They do not duplicate functionality already pro¬ 
vided by tasks. Every process contains at least one task which continues to serve as the pri¬ 
mary object of processor multiplexing. The resident portion of every process structure will 
include at least one (and probably only one) task control block. 

Creation and deletion of processes will cause the subsequent addition and removal (AddTask 
and RemTask ) of task control blocks as appropriate. Functions which control processes may, in 
the normal course of events, call task control functions. 


5.2. Context 

A process exists within the system as an independent execution environment. This means that 
the system must support a complete context for each process. 


Information maintained by the system for each process includes: 


process control 


stack 


a system structure containing kernel variables related to the state and context 
of a process. This structure contains among other things, the EXEC task 
control block (see the structure section below). 

the official process (task) stack for calling subroutines, storing variables, and 
passing parameters. The context switcher saves much of the process state on 
this stack. 


program code the native code to be executed by a process. This code may not be unique to 
just this process. It is possible for more than one process to share the same 
code. In addition some of this code may be in the form of overlays. 

program data the data area in which the process stores its data. This area is often used 
with program global data or dynamically allocated data. It is not required for 
programs that only use a stack (in such cases global data is held in the initial 
portion of the stack). 

resource tracking [punt this for now ] a linked list containing blocks of resources used by the pro¬ 
cess: file control blocks, IO blocks, message ports, libraries, memory usage, 
shared data, overlays, etc, etc, etc. 

exception code a special piece of code that is executed whenever a process exception occurs. 

This code may be unique to a process or may be shared by many similar 
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processes (as in the case of the default). By defintion this code also handles 
the process termination exception. A process may also require an exception 
vector area; this is considered part of the process data above. 

Processes run entirely in user mode. They utilize a single user mode implicit stack. A process 
may momentarily and invisibly enter supervisor mode for a very small set of system functions 
(processor scheduling for example). Processes do not require their own supervisor stack. Operat¬ 
ing system routines are well behaved (they don’t mess with the stack) and use well defined 
amounts of stack space (they don’t allocate large local variables or recurse). 


5.3. Structure 


The process structure maintained by the system contains: 


task control 


descriptor 
program name 


a task control block. This block links the process to the appropriate 
scheduler queue. This linkage may exist in parallel to other process mainte¬ 
nance linkage used by the system. Note that the task control block contains 
the task’s priority and a pointer to the task’s name. These are also used by 
the process for its priority and name. 

the processes’ global descriptor. 

the name (and perhap the path too) of the program. 


parent 


a pointer to the parent process. This may be null if the parent no longer 
exists. 


siblings 


a pointer to the next and previous sibling processes. These may be null if 
there are no siblings. 


package link 


resources 


error codes 


a pointer to the package control block if present. The package control block 
contains information regarding the program execution environment. This 
include both program and data overlays (segments). 

the header for system accounting of resources beening used by this process. 
This includes memory resources (the first block of the list may actually be 
present in this segment). 

an error code for the system function called (null if successful) and an error 
code for the last actual error encountered. 


directory info 


exceptions 


done signal 
timing 


directory related information: current directory, parent directory, directory 
file internal node pointers, as needed... 

the exception vectors for process defined exception handlers. [User defined 
exception vectors need to go elsewhere]. 

a signal sent to parent when a process terminates. 

the actual and elapsed time (to some reasonable resolution) used by the pro¬ 
cess. 


This structure may actually be divided into resident and non-resident sections. The non¬ 
resident section can be swapped to disk when the process is suspended for a some period of 
time. 
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5.4. Hierarchy 

A process progeny hierarchy is available but not enforced. The system does not require that a 
process belong to any particular family. A process may have a parent, or it may be left as an 
orphan. 

Processes can also keep track of their siblings. All processes created by the same parent can be 
linked together. 

The process hierarchy is useful for keeping track of children, especially at terminatation time. 

5.5. Initialization 

Their are three ways to create a process. It can be created entirely from scratch, allocating new 
structures and loading new code and data; it can be cloned from the parent process, creating 
data structures but sharing the parent’s code; and it can be chained from the parent, consuming 
the parents resources entirely. 

Creating a task is useful when an independent program needs to be executed in parallel. Clon¬ 
ing a process saves some time and memory when a process needs to perform operations which 
are in some way related to the parent. Chaining a process mimimizes the memory stress caused 
by the birth of a new process. 

Initialization depends on the type of process creation used, but the overall result is: 

(1) a process structure is allocated for use and initialized (this includes a task control block); 

(2) a stack is allocated; 

(3) standard input, output, and error files are opened or inherited; 

(4) code is loaded and ready to execute; 

(5) data is loaded and ready for use; 

(6) a package file (if it exists) is translated and a package control block is created; 

(7) various package specified files are preloaded; 

(8) the exception vectors are initialized; 

(9) the task is added to EXEC which schedules it to run. 

A processes’ initialization code is often overlayed. 

Arguments can be passed to a process on its stack in a manner similar to a procedure call. This 
is supported by EXEC as the standard method of task parameter passing. Of course this 
method will not satisfy all languages, so there are a couple of system functions which can be 
called to fetch process (task) parameters. 

A process, once created, can be referenced by global descriptors which is not dependent the posi¬ 
tion of the process control structure. 

[What about superuser??] 
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5.6. Finalization 

When a process terminates either normally or through some form of fault, it must carefully 
clean up its execution environment: pending operations need to be completed or cancelled, locks 
need to be released, files need to be closed, offspring need to be terminated - in general all 
resources need to be released for reuse. 

[Can a process stay loaded in memory after finalization.] 
more... 


5.7. Resource Tracking 

The system needs to track resource allocation and release for each process. 
This information is most useful when a process needs to be terminated. 


more... 


5.8. Scheduling and Dispatching 

Task scheduling and dispatching are performed by EXEC. Hooks exist within the multitasking 
kernel to call auxiliary functions before and after every task dispatch. This gives the process 
control code a chance to provide extra features at important moments. For example, the system 
may wish to keep track of a process CPU time. 


more... 


5.9. Interprocess Synchronization 

The operating system supports a mechanism of interprocess synchronization through the use of 
signals. Signals are a software form of a hardware latched control signal. This mechanism pro¬ 
vides the most primitive layer (hence also the fastest) of execution process control. To some 
degree the message, I/O, exception, and resource management mechanisms all depend upon sig¬ 
nals for process synchronization. 

Process signals are directly supported by the EXEC task signal mechanism. When a process sig¬ 
nal occurs, the process descriptor is mapped to an actual process structure, which contains a 
task control block. The EXEC Signal () function is then called to perform the necessary actions. 
As with tasks, processes may have up to 32 unique events. (See EXEC documentation) 


5.10. Interprocess Communication 

The operating system supports inter-process communications through the use of message ports. 
EXEC provides the underlying support for message ports. 
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5.10.1. Direct Messages 

Messages may be direct or buffered. 

A direct message has its node directly linked to the receiver port queue. The message content 
remains in the sender’s address space. The sender should have created this message in a shared 
segment which is accessible to the receiver. This type of message is very fast, but can be 
dangerous. If the sender process is terminated, its memory may be returned to the free pool. 
The receiver may then access an invalid memory subregion. The results of this action can be 
quite unpredictable depending on whether the message’s memory was reused by another process. 
This problem can be solved by sending and receiving messages through a shared memory subre¬ 
gion. The memory subregion will not be deallocated until both processes have concluded access. 
Be careful though: messages usually contain a reply port which must also exist in the same 
shared memory subregion. 

Another problem occurs if the message is being used by the sender while it is being read by the 
receiver, or vice versa.. Generally it is not a good idea for a sender to access its pending mes¬ 
sage until it has been returned (replied). 

Then what happens if the receiver process is terminated prematurely? The sender may access 
invalid memory and then wait forever. This problem might be solvable by adding making port 
descriptors fairly unique. 

Direct messages are supported by Exec. 


5.10.2. Buffered Messages 

A buffered message is always copied from the sender’s address space into the receiver’s address 
space. This action is slower than a direct message, but it is also safer. The system will check 
for possible problems before actually performing the transfer, e.g.: receiver process terminated. 
The sender’s copy of the message is immediately available for reuse. 

Buffered messages are supported by DOS and internally make use of the direct message mechan¬ 
ism. 


5.10.3. Ports 

Ports collect messages on a FIFO basis. Every port is given an ASCII name to aid in the rendez¬ 
vous. Ports can also be mapped to special files. 

At the DOS level, a port is accessed via a global descriptor. 
more... 


5.10.4. Replies 

To receive a message reply the sender must provide a reply port. Messages that wish a reply 
must include a pointer (or descriptor) to this reply port. 
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Operating System Specification 


5.10.5. Waiting for a Message 

A function waits for a message by waiting for the signal associated with its receiver port. 
Whenever a message is sent to that port, the signal is posted to the receiver process. 

{remote messages?} 
more... 


5.11. Mutual Exclusion 

Messages provide a cute mechanism of mutual exclusion control. 
more ... 


5.12. Timers 


more ... 


5.13. Exceptions 

(default code) for handling system, processor, and user generated exceptions. This includes the 
necessary finalization code to release all process resources: files, messages, IO, ... 

more... 


5.13.1. Processor 


more... 


5.13.2. User 


more... 


5.13.3. Signalled 


more... 


5.13.4. Defaults 


more... 

5.14. Functions 
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